TABLE OF CONTENTS

AirShopping

The AirShopping API endpoint is designed for flight search, enabling users to retrieve available flight options based on specific travel criteria. This endpoint allows clients to query flight itineraries, including both onward and return journeys, with support for multiple passengers, cabin classes, and airline preferences.


This API is ideal for integration into flight booking platforms, providing a streamlined and efficient way to access global flight content with support for complex travel scenarios.


VersionDateDescription of Edit
Beta2025/09/16Initial Commit
v1.02025/10/22AirShoppingRQ:
  • Modified promotionCriteria data structure to support multi-supplier search scenarios
AirShoppingRS:
  • Modified Price object
  • Add SSRs node to support returning optional paid ancillary services
  • Add technicalCapabilities



Request Details
Path/api/flight/connectivity/search/airShopping


Request Playload Example

Request Payload Example
{
   "flightRequests": [
       {
           "arrivalInfo": {
               "arrivalDate": "2025-09-22",
               "iataLocationCode": "BKK",
               "type": "citycode"
           },
           "cabinClass": 4,
           "departureInfo": {
               "departureDate": "2025-09-22",
               "iataLocationCode": "KUL",
               "type": "citycode"
           }
       },
       {
           "arrivalInfo": {
               "arrivalDate": "2025-09-30",
               "iataLocationCode": "KUL",
               "type": "citycode"
           },
           "cabinClass": 4,
           "departureInfo": {
               "departureDate": "2025-09-30",
               "iataLocationCode": "BKK",
               "type": "citycode"
           }
       }
   ],
   "paxList": [
       {
           "count": 1,
           "paxType": "ADT"
       },
       {
           "count": 1,
           "paxType": "CHD"
       }
   ]
}


Request Payload Schema

KeyParentTypeMandatory/OptionalDescription
flightRequestsrootArrayM
departureInfoflightRequestsObjectM
iataLocationCodedepartureInfoStringM3 uppercase letters
typedepartureInfoStringO
  • airportcode
  • citycode
How the iataLocationCode is to be interpreted, if empty, default as airportcode
departureDatedepartureInfoStringMYYYY-MM-DD
arrivalInfoflightRequestsObjectM
iataLocationCodearrivalInfoStringM3 uppercase letters
typearrivalInfoStringO
  • airportcode
  • citycode
How the iataLocationCode is to be interpreted, if empty, default as airportcode
arrivalDatearrivalInfoStringMYYYY-MM-DD
cabinClassflightRequestsIntO
  • 1 = First Class
  • 2 = Business Class
  • 3 = Premium Economy
  • 4 = Economy
currencyflightRequestsStringOOnly one currency per request

Official ISO 4217 three-letter (alpha-3) codes.
https://www.iso.org/iso-4217-currency-codes.html
flightCriteriarootObjectOThis node allows to specify flight type preference for filtering results.
flightTypeflightCriteriaIntO
  • 1 = Direct (Non-stop)
  • 2 = Connect (Connecting)
  • 3 = Through (Through-flight, same flight number throughout, ground stop involved, no plane change required)
carrierCriteriasrootArrayOThis node allows you to specify query preferences to initiate a search based on specific criteria - such as supplier or airline (using airline group name) - ensuring that the results returned directly match the intended scope.
supplierNamecarrierCriteriasStringOThis field allows you to specify airline group/s with multiple operating airlines or specific flight supplier/s to query relevant content.
airlineCodecarrierCriteriasStringOSearch for specific airline/carrier by using IATA airline code
agencyCodecarrierCriteriasStringOsearch for specific airline agency code account
promotionCriteriarootArrayOA Promotion and discount code criteria to be passed to the retailer airline that could influence returned offers
promotionCodepromotionCriteriaStringOPromotion code ID or number.
supplierNamepromotionCriteriaStringO
airlineCodepromotionCriteriaStringO
agencyCodepromotionCriteriaStringO
paxListrootArrayORules:
1. Support only from 1 to 9 PAX
2. INF PAX should have a reference to one ADT PAX
3. At least 1 ADT PAX should be present
4. Number of Infants cannot be greater than Adult PAXs
paxTypepaxListStringO
Passenger Type Code:
  • ADT 
  • TEEN 
  • CHD
  • INF
*Note: Different airlines may have varying pax type classifications and age definitions for each type. DerbySoft will provide a reference library of airline-specific passenger age criteria for Sellers. If a pax type requested by the Seller (e.g., TEEN) is not supported by the Supplier, DerbySoft will map the Seller’s requested type to a corresponding type supported by the Supplier.
countpaxListIntOThe number of passenger type


Response Schema


Key
Parent
Type
Mandatory/Optional
Description
searchResults
root
Array
O

supplier
searchResults
Object
O

supplierName
supplier
String
O

airlineCode
supplier
String
O

agencyCode
supplier
String
O

technicalCapabilities
supplier
Array
O
node provides critical information about the technical execution methods and support channels available for post-booking operations with this specific supplier. This allows you to understand how different modification requests (e.g., refunds, changes) are handled behind the scenes and set the correct user expectations
operationType
technicalCapabilities
String
M
The type of post-booking operation. This field identifies which specific operation the technical details apply to (e.g., refunding a ticket, changing a flight). It scopes the context for the subsequent technical fields.
  • DIRECT_REFUND
  • ESTIMATED_REFUND
  • CHANGE_FLIGHT_TIME
  • UPDATE_PASSENGER_NAME
  • ADD_ANCILLARY
method
technicalCapabilities
String
M
How the operation is technically executed. Key values:
  • NATIVE_API: The supplier provides a direct, automated API.
  • DS_AI_AGENT: Automation is enabled via an AI agent (e.g., RPA, robotic process).Note: This automated service may involve additional fees charged to the seller. 
  • MANUAL: The operation cannot be processed automatically. The seller must handle it offline by contacting the supplier or airline directly through their own channels 
automationLevel
technicalCapabilities
String
M
The degree of automation. This field provides a high-level, intuitive summary of the method
  • FULL
  • PARTIAL
  • NONE
apiAvailability
technicalCapabilities
String
M
This provides granular technical detail for integrators when the method is NATIVE_API
  • REALTIME: A synchronous API that provides immediate results
  • ASYNC: An asynchronous API; a request is submitted, and the result must be polled for later.
tripsInfo
searchResults
Object
M

tripKey
tripsInfo
String
M

onwardTrip
tripsInfo
Object
M

flightType
onwardTrip
Int
M
  • 1 = Direct
  • 2 = Connect
  • 3 = Through
segmentInfos
onwardTrip
Array
M
segment information list
returnTrip
tripsInfo
Object
O

airlineOffer
searchResults
Object
M

offers
airlineOffer
Array
M

supplier
offers
Object
O

offerId
offers
String
M

transInfo
offers
String
M

refTripKey
offers
String
M

brandFareName
offers
String
O

brandFareUrl
offers
String
O

availableCount
offers
Int
O

cabinClass
offers
Int
M
  • 1 = First Class
  • 2 = Business Class
  • 3 = Premium Economy
  • 4 = Economy
supportedIssueWay
offers
String
M
  • HOLD
  • INSTANT
totalPrice
offers
Object
M

totalAmount
totalPrice
String
M
The final total amount payable by the passenger. Calculation formula: TotalBaseAmount + TotalTaxFeeAmount + totalServiceFeeAmount
totalBaseAmount
totalPrice
String
M
The price of the flight ticket itself, excluding taxes and service fees. When PriceType is Gross, this amount includes commission.
totalTaxFeeAmount
totalPrice
String
M
The sum of all tax items, equal to the sum of amounts in TaxFeeDetail.
taxFeeDetail
totalPrice
Object
O

code
taxFeeDetail
String
O

amount
taxFeeDetail
String
O

type
taxFeeDetail
String
O
Enum values: 
  • AirlineTax - Standard airline taxes
  • VAT - Value added tax
  • Other - Other tax types
totalServiceFeeAmount
totalPrice
String
O

serviceFeeDetail
totalPrice
Array
O

code
serviceFeeDetail
String
O
All service fees related to flight booking - including those charged 
by non-airline suppliers, DerbySoft.
amount
serviceFeeDetail
String
O

type
serviceFeeDetail
String
O
Enum values:
  • Supplier - Supplier service fee
  • DS - DerbySoft service fee

includedInTotal
serviceFeeDetail
String
O
  • true - Already included in TotalAmount 
  • false - Not included in TotalAmount, requires additional payment

currency
totalPrice
String
M

priceType
totalPrice
String
O
Enum values: 
  • Net - Net price, base fare excludes commission
  • Gross - Gross price, base fare includes commission

commissionAmount
totalPrice
Object
O

amount
commissionAmount
String
O
Present when PriceType is Gross, indicates the commission amount included in the base fare.
commissionRate
commissionAmount
String
O
Present when PriceType is Gross, indicates the commission percentage.
currencyConversions
totalPrice
Array
O
Provided when any fee requires currency conversion, contains complete conversion information.
fromCurrency
currencyConversions
String
O

toCurrency
currencyConversions
String
O

rate
currencyConversions
String
O

appliedTo
currencyConversions
String
O

referenceCode
currencyConversions
String
O
The code(under service fee details node or tax fee details) for reference which this currencyConversions applied to. 
originalAmount
currencyConversions
String
O

convertedAmount
currencyConversions
String
O

passengerFares
offers
Array
M

paxType
passengerFares
String
M

price
passengerFares
Object
O

supportedDocumentType
passengerFares
String
O
Travel Document Types
  • P: Passport
passengerIdentifyDocumentsRequired
passengerFares
Boolean
O

fareComponents
passengerFares
Array
M

onwardTrip
fareComponents
Object
M

segmentInfos
onwardTrip
Array
M

conditions
onwardTrip
Array
O

freeServices
onwardTrip
Array
O

freeBaggages
onwardTrip
Array
O

returnTrip
fareComponents
Object
M

ssrs
offers
Array
O
SSRS node is designed to return available optional paid ancillary services that passengers can purchase in addition to their flight ticket
service
ssrs
Object
M

serviceName
service
String
M
The commercial name of the service as displayed to passengers
serviceType
service
String
M
The category of the ancillary service:
  • Baggage
  • Meal
  • PriorityBoarding
  • SpecialAssitance
  • SeatSelection
  • SportEquipment
availability
service
String
O
Indicates current available numbers of the service
data
serviceOrder
Object
O

baggageAssociations
data
Object
O
This node is ONLY present when serviceType = 'BAGGAGE'. Contains baggage-specific details
baggageId
baggageAssociations
String
O

typeCode
baggageAssociations
String
O
Type of baggage
  • CheckedIn
  • CarryOn
descTex
baggageAssociations
String
O

maximumDimensionAllowance
baggageAssociations
Object
O

heightMeasure
maximumDimensionAllowance
String
O
Maximum allowed height of the baggage
lengthMeasure
maximumDimensionAllowance
String
O
Maximum allowed length of the baggage.
linearMeasure
maximumDimensionAllowance
String
O
Maximum allowed linear dimensions (sum of dimensions)
widthMeasure
maximumDimensionAllowance
String
O
Maximum allowed width of the baggage
unitOfMeasurement
maximumDimensionAllowance
String
O
Unit of measurement for dimensions (e.g., CM, IN)
pieceAllowance
baggageAssociations
Object
O

totalQty
pieceAllowance
String
M
Total number of baggage pieces allowed
weightAllowance
baggageAssociations
String
M

maximumWeightMeasure
weightAllowance
String
M
Maximum allowed weight per baggage piece
weightUnitOfMeasurement
weightAllowance
String
M
Unit of measurement for weight (e.g., KG, LB)
seat
data
Object
O

seatId
seat
String
O

designator
seat
String
O
Referred to as airline code
deck
seat
String
O
Indicates the level or deck of the aircraft where the seat is located. 
  • Main: for the primary cabin deck
  • Upper: for the upper deck
rowNo
seat
String
O
Specifies the row number of the seat
colNo
seat
String
O
Specifies the column position or seat letter within the row
seatType
seat
Array
O
The characteristics and features of the seat. This field uses standardized codes:
  • WINDOW
  • AISLE
  • EXIT
  • MIDDLE
  • EXTRA_LEG_ROOM
  • HANDICAP_ACCESSIBLE: wheelchair accessible seat
servicePsgFare
ssrs



paxType
servicePsgFare



unitPrice
servicePsgFare



totalAmount
unitPrice



servicePsgFare
unitPrice



eligibleTrips
ssrs
Object
M
Indicates which specific trip segments this service applies to. Multiple serviceOffers are returned when a service is available for different trips.
onwardTrip
eligibleTrips
Object
O

segmentSequence
onwardTrip
Array
O
Segment sequence numbers in the onward trip that this service applies to
returnTrip
eligibleTrips
Object
O

segmentSequence
onwardTrip
Array
O
Segment sequence numbers in the return trip that this service applies to
eligibleLeg
ssrs
Object
O
For multi-leg segments (flights with stopovers), specifies which specific leg within a segment the service applies to. Empty for non-stop flights.
legSequence
eligibleLeg
String
M

error
root
Object
O

   

  • Each search result consists of two primary components: the trip information (tripinfo) and the available offers.
    • The tripinfo section primarily contains the itinerary details, including but not limited to departure and arrival times, marketing carrier, and operating carrier.
    • The offers section, meanwhile, provides the comprehensive pricing for the entire itinerary (e.g., the total cost for one adult and one child if requested), a breakdown of fares by passenger type, along with details on bundled services and the associated change and cancellation policies.
  • OfferID Persistence
    • The offerId within the offer object is a mandatory unique identifier for the specific itinerary.
    • You must store this value. It is a required reference key for subsequent API calls, specifically the OfferPrice and OrderCreate requests, to uniquely identify the chosen offer.